<html>
  <head>
    <link href="../enzo.css" rel="stylesheet" type="text/css">
    <title>Enzo user's guide: analyzing the output</title>
  </head>
<body>
<h1>Analyzing Enzo output</h1>
Analyzing the output from an Enzo AMR simulation is more difficult because of
the complicated grid structures.  However a number of tools have been developed
to help. First, as pointed out in the section on the output format, since
each grid is it's own self-contained HDF file, each grid can be analyzed
by itself with any tool that reads HDF (IDL, Transform, etc.). Unfortunately,
for simulations with hundreds or thousands of grids this is of little assistance.
More practically, here are some other analysis methods, most of which assume
that you are doing a 3D simulation (and often that it is a cosmological
simulation).
<ol>
<li>
<b><a href="#2D projections">2D projections</a> </b>- The code has the
built-in ability to make two-dimensional projections, at a specified resolution,
of a number of quantities (tailored for cosmology) along any axis of a
given three-dimensional region. The resulting 2D HDF SDS's can then be
imaged with a number of tools, including IDL.</li>

<li>
<b><a href="#Extractions">Extractions</a> </b>- A region (generally 3D,
but this option also works for 1 and 2-dimensions) can be extracted with
a uniform resolution and saved as a single grid. This is useful for other
packages developed for single-grid codes. This option is built into
the Enzo code.</li>

<li>
<a href="#Peakfinder"><b>Peakfinder</b> </a>- In the analysis package (amr_mpi/anyl),
there is a routine which can find peaks in the baryon or dark-matter distribution,
subject to a number of qualifications (such as minimum separation).&nbsp;
[Note: enzohop is recommended for most peak finding].</li>

<li>
<b><a href="#halofinder">Hop halo finder</a> </b>- Also in the analysis
package is a version of Eisenstein &amp; Hut's hop halo finder, as applied
to the dark matter.</li>

<li>
<b><a href="#Profiler">Profiles</a></b> - Radial profile of density and
many other quantities can be generated with another analysis routine, given
an object's position.</li>

<li>
<b><a href="#Particle Representation">Particle representation</a></b> -
The code also has the ability to convert the grid into a set of particle
positions and densities, temperatures, etc. This can then be read into
a particle-analysis code.</li>
</ol>

<hr WIDTH="100%">
<br>(Note: in this section we drop the "mpirun -np 1" that is required
to run MPIprograms.&nbsp; Note also that all analysis programs only function
with one processor -- they are not parallelized.&nbsp; Finally, the square
brackets [] used below imply an optional argument and are not meant to
be typed.)
<h3>
<a NAME="2D projections"></a>2D projections</h3>
The projection is done with the Enzo code itself and is of the following
format:
<p><tt>enzo -p <i>dim</i> [-l <i>level</i>] [-m] [-b <i>point1</i>] [-f
<i>point2</i>]
<i>enzo_filename</i></tt>
<p>an example might be:
<p><tt>enzo -p 1 -l 6 -b 0.4 0.4 0.4 -f 0.6 0.6 0.6 data0015</tt>
<p>The -p option, which specifies the dimension along which the projection
is to occur, and the Enzo output_filename are the only arguments required.
The projection dimension (<i>dim</i>) is an integer from 0 to 2, and indicates
along which dimension the projection occurs. For example, a projection
along axis-0 produces an image with y-z axis.
<p>The -l option specifies the resolution of the image, by indicating a
level at which the projection will occur. The integer value <i>level </i>is
zero-based so <tt>-l 0</tt>&nbsp; produces an image with the same resolution
as the root grid. Levels larger than the maximum in the output_filename
may be used. The default value is 0.
<p>The -m option smooths the image by doing a linear interpolation between
coarse-grid points. If this option is not invoked, the result will be pixelated
in regions in which the pixels are smaller than the grid cells (although
this may be useful information). This option takes somewhat longer. The
default is no smoothing.
<p>Finally, there are two ways to specify the three-dimensional region
in which the projection is to occur, one of which is shown in the commend-line
above. This uses the -b and -f (begin and finish) flags. These flags each
take a triplet (in 3D) of floats which specify the the two corners of the
projection volume. The units are those of the problem (set by DomainLeftEdge
and DomainRightEdge). For cosmology problems, this means numbers that range
from 0 to 1. The default is the entire domain.
<p>The other mechanism for specifying the projection volume is to specify
coordinate indexes. This is done with the -s and -e flags, each of which
take a triplet of integers. The integers refer to index positions (zero-based)
within that level. This means the numbers should range between 0 and n*r^l-1
where n is the size of the top grid, r is the refinement factor and l is
the level. The advantage of this method is that the size of the region
can be precisely set, the disadvantage is the calculation is a bit more
difficult. Although these two methods can be mixed (by specifying one corner
with one method and the other corner with the other method), it is undefined
to specify one corner twice. Finally, the error checking on these values
is not great, and specifying a region with negative volume or one that
goes off the edge may result in a core dump rather than an error message.
<p>The result is placed in the file amr.project and consists of 2D scientific
data sets (HDF format) of the following quantities (subject to change):

    <ul>
      <li>baryon density (M(solar)/Mpc^3)</li>
      <li>a field proportional to the bolometric free-free emission (but see below)</li>
      <li>dark matter density (M(solar)/Mpc^3)</li>
      <li>temperature (K, weighted by free-free emission)</li>
      <li>maximum level along projection</li>
      <li>the y-parameter of thermal SZ effect</li>
      <li>the DT/T value of the kinematic SZ effect</li>
      <li>The mean density-weighted fractional metallicity of the gas along the line
	of sight</li>
      <li>The star particle density (M(solar)/Mpc^3)</li>
    </ul>

If there is a file called "ProjectionParameters" in the same directory,
then this file is opened and searched for parameters relating to the generation
of the X-ray emission field.&nbsp; The following parameters (specified
with the usual conventions: Parameter = ...) are recognized: <tt>XrayLowerCutoffkeV</tt>,
<tt>XrayUpperCutoffkeV</tt>
and <tt>XrayTableFileName</tt>.&nbsp; The first two specify the X-ray band
(observed at z=0) to be used, and the last gives the name of an ascii file
that contains the X-ray spectral information.&nbsp; A gzipped version of
this file good for bands within the 0.1 - 20 keV range is available in
amr_mpi/exe/lookup_metal0.3.data.gz.&nbsp; If these parameters are specified,
then the second field is replaced with integrated emissivity along the
long of sight in units of 10^-23 erg/cm^2/s.&nbsp; Also, see below in the
profiling section.
<p>
<hr WIDTH="100%">

<h3><a NAME="Extractions"></a>Extractions</h3>
The command-line for an extraction is very similar to a projection:
<p><tt>enzo -x&nbsp;</tt> <tt>[-l <i>level</i>] [-b <i>point1</i>] [-f
<i>point2</i>]
<i>enzo_filename</i></tt>
<p>The&nbsp; meaning of the level (-l) and region (-b, -f) flags are the
same as for the projection (see above).
<p>The output is a standard grid file and so consists of an HDF file with
a number of scientific data sets.&nbsp; The scientific data sets are named
and have dimensional axis.&nbsp; The units are code units with the exception
of temperature, with is in degrees K.&nbsp; See the file CosmologyGetUnits.C
for a definition of code units, or look in the ascii output file (search
for lines which start DataCGSConversionFactor = ...).
<p>
<hr WIDTH="100%">

<h3><a NAME="Peakfinder"></a>Peakfinder</h3>
The peakfinder is part of the <tt>amr_mpi/anyl</tt> package and is
the executable <tt>bin/findpeaks</tt>.

It is run with the command-line:
<p><tt>findpeaks [-n <i>number</i>] [-m <i>min_density</i>] [-s <i>separation</i>]
<i>enzo_filename peak_filename</i></tt>
<p>The algorithm reads in the Enzo output file <i>enzo_filename</i> and looks
for peaks (a density larger than it's 26 neighbours) in the baryon density
distribution.&nbsp; The result is output as a series of locations (float
triplets between 0 and 1) to the file <i>peak_filename, </i>sorted by the
peak density.
<p>The -n option takes an integer argument and returns the <i>number</i>
largest peaks.&nbsp; Default: 1
<p>The flag -m tells the algorithm to only check peaks with densities
larger than the float value <i>min_density</i> which, for cosmology, is
in units of the mean density of non-relativistic mass (at the redshift
at which the output occurred).&nbsp; This option is mostly useful for speeding
up the algorithm, since a large value for the minimum density can drastically
cut down the number of cells that need to be checked.&nbsp; Default: 1
<p>The last option, -s,&nbsp; specified the minimum separation between
peaks (the lower density peak is discarded), and the float value <i>separation</i>
should be in terms of comoving Mpc/h.&nbsp; Default: 0
<p>This peakfinder really does just find local peaks -- a halo finder (see
below) is probably what you're looking for.
<p>
<hr WIDTH="100%">

<h3><a NAME="halofinder"></a>Halofinder</h3>
The halo finder is part of the analysis package.&nbsp; It
uses the hop algorithm (and source code) developed by Daniel Eisenstein
and Wayne Hu (<a href="http://arXiv.org/abs/astro-ph/?9712200">astro-ph/9712200</a>)
-- thanks to them for making the code available.&nbsp; The compilation
is currently a bit convoluted because hop assumes 4 byte floats.&nbsp;
This means that you must compile everything in single precision; change
the PRECISION = r8 macro to PRECISION = r4 (in both amr_mpi/src/Makefile
and amr_mpi/anyl/Makefile).&nbsp; Then compile enzo (make clean first if
previously compiled with PRECISION = r8), and then compile enzohop: "cd
amr_mpi/anyl; make enzohop".&nbsp; Run with:
<p><tt>enzohop [-b #] [-f #] [-t #] [-g] [-d] </tt><i>enzo_filename</i>
<p>The only required argument, <i>enzo_filename,</i> is the name of an Enzo
output file.
<p>The optional flags that specify a region to work on (-b for begin and
-f for finish) are as described in the projection section.&nbsp; Default:
the whole region
<p>The next flag (-t) takes a float and specifies the most important threshold
used in hop (the outer density definition).&nbsp; Default: 160
<p>The -g flag indicates that baryon grid points should be converted to
particles and passed into hop (along with the dark matter).&nbsp; This
is not recommended.&nbsp; Finally, the -d flag is the usual debugging flag.
<p>The output is placed into a number of files, only one of which is described
here (see hop for the others).&nbsp; HopAnalysis.out contains a list of
the results groups, their particle number, mass and the location of the
densest particle.
<p>
<hr WIDTH="100%">

<h3><a NAME="Profiler"></a>Profiler</h3>
It is often useful to compute azimuthally-averaged radial profiles.&nbsp;
The utility <tt>bin/enzo_anyl </tt>can be used for this.&nbsp;
It runs
with the command-line:
<p><tt>enzo_anyl&nbsp;</tt> <i>enzo_filename&nbsp;&nbsp; anyl_parameter_file</i>
<p>The first argument, <i>enzo_filename</i>, is the name of an Enzo output
file, and the second argument is the name of an ascii file which contains
some parameters for the analysis routine.&nbsp; An <a href="AnalyzeClusterParameterFile">example
</a>of
this file should be in <tt>amr_mpi/anyl/AnalyzeClusterParameterFile</tt>.&nbsp;
The format of the parameters is the same as for the enzo code itself.&nbsp;
The parameters are:
<ul>
<li>
<b>Rinner </b>- The inner edge of the profile in comoving Mpc.&nbsp; Default:
0.0001 of the ComovingBoxSize</li>

<li>
<b>Router</b> - The outer edge of the profile in comoving Mpc.&nbsp; This
should be well outside the expected virial radius of the object.&nbsp;
Default: 0.1 of the ComovingBoxSize</li>

<li>
<b>CenterPosition</b> - A triplet of floats from 0 to 1 specifying the
location of the center.&nbsp; This parameter is ignored if CenterListName
is set.&nbsp; Default: if left unspecified, the location of the maximum
density in the volume is used.</li>

<li>
<b>NumberOfPoints</b> - An integer: the number of points in the profile.&nbsp;
The radial shells are spaced in equal logarithmic intervals in radius (except
for the first point)&nbsp;&nbsp; Default: 16</li>

<li>
<b>VirialDensity</b> - This float indicates the overdensity, relative to
the critical (not mean) density, that is to be used to define the virial
radius.&nbsp; Default: 200</li>

<li>
<b>CenterListName </b>- The name of a file containing a list of center
positions (each line should contain a triplet of floats, between 0 and
1).&nbsp; Up to 1000 positions may be specified.&nbsp; If not set, then
the parameter CenterPosition is used to define a single center.&nbsp; Default:
NULL</li>

<li>
<b>MeanVelocityVirialFraction</b> - This is the fraction of the virial
radius which is used to determine the mass-weighted mean velocity of the
object.&nbsp; It can be useful to set this significantly less than the
1.0 (i.e. the virial radius) if the center of the object is moving relative
to the center-of-motion of the entire object.&nbsp; Default: 1.0</li>

<li>
<b>XrayLowerCutoffkeV</b> - If this and the next three parameters are specified,
then an accurate calculation of the X-ray emissivity is made.&nbsp; This
parameter and the next indicate the X-ray band (in keV at z=0) that is
to be used in the calculation. Default: none</li>

<li>
<b>XrayUpperCutoffkeV</b> - The high energy end of the X-ray band in keV.&nbsp;
Default: none</li>

<li>
<b>XrayTableFileName</b> - The name of the ascii file which contains the
spectral lookup table.&nbsp; There is a version computed with a Raymond-Smith
code for a low density hot gas with a metallicity of 0.3 relative to solar
in the file amr_mpi/exe/lookup_metal0.3.data.gz.</li>

<li>
<b>ComputeDiskInformation</b> - This toggle flag (1 is on, 0 off) controls
whether a disk profile and image is generated.&nbsp; If yes, then the angular
momentum vector of the dense gas (see below) is used to define a disk.&nbsp;
Default: 0</li>

<li>
<b>DiskImageSize</b> - The number of pixels on a side in the three disk
images (face, and two sides) which are computed if the above flag is turned
on.&nbsp; Default: 100</li>

<li>
<b>DiskRadius</b> - This is the fraction of the virial radius which the
disk image comprises (i.e. each pixel is of size r_virial*DiskRadius/DiskImageSize).&nbsp;
Default: 0.2</li>

<li>
<b>LowerDensityCutoff </b>- This is lower density cutoff (in Msolar/Mpc^3)
for material to be counted as dense for the calculation of the "dense"
angular momentum gas, the cold fraction and the dense fraction.&nbsp; Default:
1e14</li>

<li>
<b>UpperDensityCutoff </b>- The maximum density (in Msolar/Mpc^3) for gas
to be counted in the "dense" angular momentum.&nbsp; Default: 1e35</li>

<li>
<b>ColdTemperatureCutoff </b>- The highest temperature (in K) for gas to
be considered cold.&nbsp; Used in the calculation of the "dense" angular
momentum gas and in the cold fraction.&nbsp; Can be over-written by the
following parameter.&nbsp; Default: 15000</li>

<li>
<b>ColdTemperatureCutoffVirialFraction </b>- If set, this parameter sets
ColdTemperatureCutoff (for each cluster) to this value times the predicted
virial temperature (see below).&nbsp; Default: none</li>

<li>
<b>VirialTemperatureNormalize</b> - The normalization of the predicted
virial temperature relation (mass - temperature - redshift relation), relative
to that in Bryan &amp; Norman (1998).&nbsp; If the virial mass is > 1e8
solar masses then mu (the mean mass per particle) is set to 0.6, otherwise
mu=1.22.</li>
</ul>
The output is a set of files starting with <tt>AnalyzeCluster</tt>.&nbsp;
If the CenterListName was set, then they are numbered with a three digit
identifier (<tt>AnalyzeCluster000</tt>, etc.).&nbsp; Each profile produces
for (or more) files, the first contains general information as well as
the baryon profile and has no suffix.&nbsp; Then there are three more which
have the suffixes <tt>.DarkMatter, .Species</tt> and <tt>.Inertial</tt>,
which contain profile relating to the particles, the multiple species (if
used) and the inertial tensors of the gas and particles.&nbsp; Finally,
two other disk profiles may be generated if requested (see parameters above).
<p>Each file consists of description information with the pound symbol
(i.e. a comment) at the start of the line, and then the profile itself.&nbsp;
The first column is the center of the bin, while the second column is the
right edge of the bin, in terms of Mpc (note: not comoving Mpc/h).
<p>Virial information is also included in <tt>AnalyzeCluster,</tt> (mass,
radius, mean velocity within, etc.), and each file contains a line which
gives the mean of the profile quantities within the virial radius.
<p>
<hr WIDTH="100%">

<h3><a NAME="Particle Representation"></a>Particle Representation</h3>
To turn the grid points into particles, use the command-line:
<p><tt>enzo -o&nbsp;</tt>&nbsp; <i>enzo_filename</i>
<p>This will create two HDF files, one called amr.particles.gas and the
other amr.particles.dm which contain one-dimension scientific data sets
of the "particle" positions, velocities, radii, density, temperature, etc.
<p>This description will be lengthened if interest is expressed in this
format.&nbsp; Note that there is a version which outputs ascii files called
dumpgrids (in amr_mpi/anyl).&nbsp; Again, this is under development and
is intended for conversion to other analysis/visualization programs.
<br>

<p>&nbsp;</p>
<p><a href="../index.html">Go to the Enzo home page</a></p>

<hr WIDTH="100%">
<center>&copy; 2004 &nbsp; <a href="http://cosmos.ucsd.edu">Laboratory for Computational Astrophysics</a><br></center>
<center>last modified February 2004<br>
by <a href="mailto:bwoshea (AT) lanl.gov">B.W. O'Shea</a></center>

</body>
</html>
